OData Endpoints

Portfolio OData API Documentation

A complete description of OData API endpoints, including the fields returned by a query, can be found at https://documenter.getpostman.com/view/11307535/T17Q6QJe?version=latest

Where the online documentation differs from this document, the online version should be considered correct.

Base URL

The documentation presents the relative URL to the base URL specific to a client’s OData service endpoints.

The service endpoint (OData URL) can be found in the OData User Account under Account Settings on the Portfolio Home Page. (Portfolio > Account Settings > OData Password).

The Base URL typically ends with the version number, e.g. https://localhost/sp-odata/v1/

Authorization

All API resources have a parent portfolio, and users should have permissions for the portfolio to access any API resource.

Authorization requires the OData username and password, and uses the ‘Basic Auth‘ scheme.

The documentation presents the relative URL to the base URL specific to a client’s OData service endpoints.

For example:

Base URL: http://localhost/sp-odata/v1/

Documented Endpoint URL: /$metadata

Combined URL to access the endpoint: http://localhost/sp-odata/v1/$metadata

Metadata

/$metadata

Get metadata describes the structure and organization of all data resources exposed by the Portfolio OData API.

The format follows the OData version 4.0 Standard, always returned as application/xml.

Portfolios

/portfolios

Lists all portfolios the authenticated user has access permission for.

Portfolio

/portfolios({portfolio Id})

Get a specific portfolio specified by {portfolio Id}.

The authenticated user should have access permission for the portfolio.

Portfolio Timeperiods

/portfolios({portfolio Id})/timeperiods

List all time periods of portfolio {portfolio Id}, ordered by 0-based time period index. The first time period has index 0. The time periods are referenced by its index. All time series value (type TimePeriodValue) use this index to identify the corresponding the time period.

Portfolio DataVersions

/portfolios({portfolio Id})/dataversions

List all data versions of portfolio {portfolio Id}.

A scenario can use different input data by specifying the data version.

Portfolio NameSpaces

/portfolios({portfolio Id})/namespaces

List all namespace of portfolio {portfolio Id}.

A namespace is used to distinguish different opportunities having the same name, and organizes opportunities of a portfolio. Each opportunity belongs to a namespace (or default namespace) and opportunity name should be unique among opportunities in a same namespace.

Portfolio Attributes

/portfolios({portfolio Id})/attributes

List all attributes (type Attribute) of portfolio {portfolio Id}.

Portfolio Metrics

/portfolios({portfolio Id})/metrics

List all metrics (type Metric) of portfolio {portfolio Id}.

Portfolio MetricSets

/portfolios({portfolio Id})/metricsets

List all metric sets of portfolio {portfolio Id}.

A metric set defines a collection of metrics of the portfolio.

Users can create a metric set from Portfolio Web by adding a dashboard, all the metrics added to the dashboard defines a metric set. There are also some system defined metric sets, like 'Input Metrics', 'Master Data Metrics'.

Portfolio Opportunities

/portfolios({portfolio Id})/opportunities

List all opportunities (type Opportunity) of portfolio {portfolio Id}.

Portfolio Scenarios

/portfolios({portfolio Id})/scenarios

List all scenarios (type Scenario) of portfolio {portfolio Id}.

Portfolio ScenarioContributionExports

/portfolios({portfolio Id})/scenarioContributionExports

List all scenario-contribute-exports (type ScenarioContributionExport) of portfolio {portfolio Id}.

Users need to select 'Database' as the export destination when they export opportunity contributions fromPortfolio Web UI. Once the export job is done, the result will be available on this list.

Attribute

/attributes(portfolioId={portfolio Id}, id={attribute Id})

Get a specific portfolio attribute specified by attributes(portfolioId={portfolio Id}, id={attribute Id}).

See Portfolio Attributes to list all attributes of the portfolio.

Attribute Characteristics

/attributes(portfolioId={portfolio Id}, id={attribute Id})/characteristics

List all characteristics of an attribute specified by attributes(portfolioId={portfolio Id}, id={attribute Id}).

See Portfolio Attributes to list all attributes of the portfolio.

A characteristic of an attribute represents a named value of the attribute. A characteristic has three possible value properties corresponding to each value type, and only the value property of the value type has value.

Metric

/metrics(portfolioId=1,Id=1)

Get a specific portfolio metric specified by metrics(portfolioId={portfolio Id},Id={metric Id}).

See Portfolio Metrics to list all metrics.

MetricSets

/metricSets(portfolioId=1,id=-2)

Get a metric set of a portfolio, specified by metricSets(portfolioId={portfolio Id},id={metricSet Id}).

See Portfolio MetricSets to list all metric sets of the portfolio.

MetricSet Metrics

/metricSets(portfolioId=1,id=-2)/metrics

List all metrics (type Metric) in a metric set, specified by metricSets(portfolioId={portfolio Id},id={metricSet Id}).

See Portfolio MetricSets to list all metric sets of the portfolio.

Opportunity

/opportunities(portfolioId=1,id=2)

Get an opportunity specified by opportunities(portfolioId={portfolio Id},id={opportunity Id}).

See Portfolio Opportunities to list all opportunities of the portfolio.

Opportunity Outcomes

/opportunities(portfolioId=1,id=15)/outcomes

List all outcomes of an opportunity specified by opportunities(portfolioId={portfolio Id},id={opportunity Id}).

See Portfolio Opportunities to list all opportunities of the portfolio.

Each outcome provides input data of a specific data version and all outcomes of a specific data version will be used together for calculating opportunity results.

Opportunity Characteristics

/opportunities(portfolioId=1,id=14)/characteristics

List all characteristics of an opportunity specified by opportunities(portfolioId={portfolio Id},id={opportunity Id}).

See Portfolio Opportunities to list all opportunities of the portfolio.

Opportunity characteristics are mainly used for selecting master data by characteristics matching rule.

An opportunity characteristic represents the opportunity's value of an attribute. There may be only one opportunity characteristic for an attribute.

Portfolio OpportunityResults

/portfolios(1)/opportunityResults(metricId=1,dataVersionId=null)

Get the metric (specified by metricId=) results of all opportunities of a portfolio (specified by portfolios({portfolio Id})) with input data version (specified by dataVersionId={dataVersion Id}.

See Portfolio DataVersions to list all data versions of the portfolio. For default data version, use dataVersionId=null or dataVersionId=null.

Both the metric and data version should belong to the portfolio.

The Portfolio OpportunityResults returns a list of 'Values' which are a list of 'TimePeriodValue'.

Portfolio OpportunityInputResults

/portfolios(1)/opportunityInputResults(dataVersionId=null)

Get all the input metric values of all opportunities of a portfolio, specified by portfolios({portfolio Id}).

The response format is the same as Portfolio OpportunityResults.

Scenario

/scenarios(2)

Get a scenario specified by scenarios({scenario Id}).

See Portfolio Scenarios to list all scenarios of the portfolio.

Scenario OpportunityInputResults

/scenarios(1)/opportunityInputResults

Get all the input metric values of all opportunities for a scenario specified by scenarios({scenario Id}).

The input data used are from the data version selected by the scenario.

The response format is the same as Portfolio OpportunityResults.

Scenario Characteristics

/scenarios(12)/characteristics

Get the characteristics of a scenario specified by scenarios({scenario Id}).

Scenario characteristics will be augmented to all opportunities characteristics when selecting matching master data.

Scenario Selections

/scenarios(2)/selections

Get the selection time series of opportunities selected by a scenario specified by scenarios({scenario Id}).

The length of the selection time series is the planning horizon, and the first time period is the first of the portfolio time periods. Only the opportunities selected in at least one time period will have entry. If an opportunity is not listed here, it is not selected at all by the scenario.

Scenario Result

/scenarios(1)/result(metricId=32)

Get the current result of a scenario specified by scenarios({scenario Id}), for a metric specified by (metricId={metric Id}).

The length of the value time series is the same as portfolio time periods and the time series array index is the time period index.

Scenario Results

/scenarios(1)/results(metricSetId=4)

Get the current results of a scenario specified by scenarios({scenario Id}), for all metrics of a metric set specified by (metricSetId={metricSet Id}).

The response format is the same as Scenario Result.

Scenario ResultGroupBy

/scenarios(1)/resultGroupBy(metricId=8,attributeId=5)

Get the current results of a scenario (specified by scenarios({scenario Id})), grouped by an attribute (specified by attributeId={attribute Id})) values for a metric specified by metricId={metric Id}.

Each group represents all the selected opportunities with the same characteristics for the attribute.

Scenario ResultsGroupBy

/scenarios(1)/resultsGroupBy(metricSetId=4,attributeId=5)

Get the current results of a scenario specified by scenarios({scenario Id}), grouped by an attribute (specified by attributeId={attribute Id})), for all metrics in a metric set specified by metricSetId={metricSet Id}.

The response format is the same as Scenario ResultGroupBy.

Scenario ForwardModelingResults

/scenarios(1)/forwardModelingResults

List all forward modeling results of a scenario specified by scenarios({scenario Id}).

ForwardModelingResult

/forwardModelingResults(scenarioId=1,id=1004)

Get a forward modeling result specified by (scenarioId={scenario Id},Id={result Id}).

See Scenario ForwardModelingResults to list all results of the scenario.

ForwardModelingResult MetricStatistics

/forwardModelingResults(scenarioId=2,id=5)/metricStatistics

Get all the metric value statistics of a forward modeling result specified by (scenarioId={scenario Id},Id={result Id}).

ScenarioContributionExport

/scenarioContributionExports(1)

Get a scenario result contribution data export specified by scenarioContributionExports({export Id}).

See Portfolio ScenarioContributionExports to list all exports of the portfolio.

ScenarioContributionExport TimePeriods

/scenarioContributionExports(1)/timePeriods

List the time periods of a scenario contribution export specified by scenarioContributionExports({export Id}).

These are the time periods at the moment exporting executed; use this for interpreting exported time series values because the source scenario and portfolio can keep changing.

ScenarioContributionExport OpportunityAttributes

/scenarioContributionExports(1)/opportunityAttributes

List all opportunity characteristics exported by a scenario contribution export specified by scenarioContributionExports({export Id}).

These are the attribute values of opportunities selected at the moment exporting executed, use this for interpreting exported time series values because the source scenario and portfolio can keep changing.

ScenarioContributionExport OpportunityContributions

/scenarioContributionExports(1)/opportunityContributions

List all opportunity (or instance) contribution values of a scenario contribution export, specified by scenarioContributionExports({export Id}).

If the user selected Total for Opportunity Contribution Level, then each item represents an opportunity total contribution. If the user selected Selection Period, then each item represents the contribution of a time period instance of the opportunity.

AllPortfolios

/AllPortfolios

Lists all portfolios (type AllPortfolio) the authenticated user has access permission for.

Flat view type for Portfolio to support old OData version clients, especially Spotfire. No support for latest OData navigational features.

AllPortfolioTags

/AllportfolioTags

Lists all tags of all portfolios accessible by the current user.

Flat view type for Portfolio to support old OData version clients, especially Spotfire. No support for latest OData navigational features.

AllPortfolioComments

/AllPortfolioComments

Lists all comments of all portfolios accessible by the current user.

Flat view type for Portfolio to support old OData version clients, especially Spotfire. No support for latest OData navigational features.

AllAttributes

/AllAttributes

Lists all attributes of all portfolios accessible by the current user.

Flat view type for Portfolio to support old OData version clients, especially Spotfire. No support for latest OData navigational features.

AllCharacteristics

/AllCharacteristics

Lists all characteristics of all attributes of all portfolios accessible by the current user.

Flat view type for Portfolio to support old OData version clients, especially Spotfire. No support for latest OData navigational features.

The properties having the Filter? column No cannot be used as a filter ($filter). You cannot use these properties for a Spotfire 'On-Demand input parameter'.

AllMetrics

/AllMetrics

Lists all metrics of all portfolios accessible by the current user.

Flat view type for Portfolio to support old OData version clients, especially Spotfire. No support for latest OData navigational features.

AllDataVersions

/AllDataVersions

Lists all data versions of all portfolios accessible by the current user.

Flat view type for Portfolio to support old OData version clients, especially Spotfire. No support for latest OData navigational features.

AllNamespaces

/AllNamespaces

Lists all namespaces of all portfolios accessible by the current user.

Namespaces are used to distinguish different opportunities having the same name on import, and they enforce uniqueness of opportunities in a portfolio. Each opportunity belongs to a namespace (or default namespace) and the opportunity name should be unique among opportunities in the same namespace.

Flat view type for Portfolio to support old OData version clients, especially Spotfire. No support for latest OData navigational features.

AllOpportunities

/AllOpportunities

Lists all opportunities of all portfolios accessible by the current user.

Flat view type for Portfolio to support old OData version clients, especially Spotfire. No support for latest OData navigational features.

AllOpportunityCharacteristic

/AllOpportunityCharacteristics

Lists all characteristics of all opportunities of all portfolios accessible by the current user.

Opportunity characteristics are mainly used for selecting master data by characteristics matching rule.

An opportunity characteristic represents the opportunity's value of an attribute. There may be only one opportunity characteristic for an attribute.

CharacteristicName is always a string value of the attribute. The value is repeated under the appropriate ValueType for conversion in client applications.

Flat view type for Portfolio to support old OData version clients, especially Spotfire. No support for latest OData navigational features.

AllScenarios

/AllScenarios

Lists all scenarios of all portfolios accessible by the current user.

CalcVersionTag identifies all the data used for the scenario calculation. All changes to scenario and/or portfolio data creates a new tag. Any scenario calculation results having a tag different from the scenario's current tag are interpreted as 'obsolete'. So, this tag can be used to query for only current calculation results, like forward modeling results, scenario result exports.

Flat view type for Portfolio to support old OData version clients, especially Spotfire. No support for latest OData navigational features.

AllScenarioCharacteristics

/AllScenarioCharacteristics

Lists all characteristics of all scenarios of all portfolios accessible by the current user.

Scenario characteristics will be augmented to all opportunities characteristics when selecting matching master data.

The properties having the Filter? column No cannot be used as a filter ($filter). You cannot use these properties for a Spotfire 'On-Demand input parameter'.

Flat view type for Portfolio to support old OData version clients, especially Spotfire. No support for latest OData navigational features.

AllSelections

/AllSelections

Lists all selection values of all scenarios of all portfolios accessible by the current user.

Only opportunity and time-period pairs with non-zero selection values will have this record. If an opportunity is not listed here, it is not selected by the scenario.

The properties having the Filter? column No cannot be used as a filter ($filter). You cannot use these properties for a Spotfire 'On-Demand input parameter'.

Flat view type for Portfolio to support old OData version clients, especially Spotfire. No support for latest OData navigational features.

AllForwardModelingResults

/AllForwardModelingResults

Lists all forward modeling results of all portfolios accessible by the current user.

(*) ‘Obsolete’ tagged results older than the configured threshold will be deleted. (Application Server Settings)

Flat view type for Portfolio to support old OData version clients, especially Spotfire. No support for latest OData navigational features.

AllForwardModelingMetricStatistics

/AllForwardModelingMetricStatistics

Lists all metric value statistics of all forward modeling results accessible by the current user.

The properties having the Filter? column No cannot be used as a filter ($filter). You cannot use these properties for a Spotfire 'On-Demand input parameter'.

Flat view type for Portfolio to support old OData version clients, especially Spotfire. No support for latest OData navigational features.

AllScenarioResultExports

/AllScenarioResultExports

Lists all scenario result exports accessible by the current user.

Each export entity contains scenario results and contributions by opportunities selected by the scenario.

All properties represent the data snapshot at the moment a user exports, which may be different than the last calculation. Use DataVersionId across endpoints to verify that results and data version match.

Whenever user exports scenario results, all previous exports of the same scenario and/or portfolio will be checked to see if they are out of date, and they will be marked Obsolete.

(*) ‘Obsolete’ tagged results older than the configured threshold will be deleted. (Application Server Settings)

The export entity will be created when the 'Rows' storage and 'Database' destination options are selected when exporting opportunity contributions.

This endpoint requires that the ExportDatabase server setting is configured. Otherwise, a 403 Forbidden error is the result.

Flat view type for Portfolio to support old OData version clients, especially Spotfire. No support for latest OData navigational features.

AllScenarioResultValues

/AllScenarioResultValues

Lists all scenario values for each metric and time-period, of all scenario result exports accessible by the current user.

Flat view type for Portfolio to support old OData version clients, especially Spotfire. No support for latest OData navigational features. To download all values satisfying a specific query, the OData client must start from the first page (no $skip) and continue, following the odata.nextLink. No random $skip query option is allowed in Spotfire.

The properties having the Filter? column No cannot be used as a filter ($filter). You cannot use these properties for a Spotfire 'On-Demand input parameter'.

This endpoint does not support $orderby, $count query options.

This endpoint requires that the ExportDatabase server setting is configured. Otherwise, a 403 Forbidden error is the result.

AllScenarioResultContributions

/AllScenarioResultContributions

Lists all contribution values for each metric and time-period, of all scenario result exports accessible by the current user.

Flat view type for Portfolio to support old OData version clients, especially Spotfire. No support for latest OData navigational features. To download all values satisfying a specific query, the OData client must start from the first page (no $skip) and continue, following the odata.nextLink. No random $skip query option is allowed in Spotfire.

The properties having the Filter? column No cannot be used as a filter ($filter). You cannot use these properties for a Spotfire 'On-Demand input parameter'.

This endpoint does not support $orderby, $count query options.

This endpoint requires that the ExportDatabase server setting is configured. Otherwise, a 403 Forbidden error is the result.

AllResultTimePeriods

/AllResultTimePeriods

Lists all time-periods of all scenario result exports accessible by the current user.

This endpoint requires that the ExportDatabase server setting is configured. Otherwise, a 403 Forbidden error is the result.

Flat view type for Portfolio to support old OData version clients, especially Spotfire. No support for latest OData navigational features.